home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 2 / CU Amiga Magazine's Super CD-ROM 02 (1996)(EMAP Images)(GB)[!][issue 1996-04].iso / magazine / amiga_e / epp / docs / epp.doc next >
Text File  |  1980-01-05  |  15KB  |  377 lines
  1. ============================================================================
  2.  
  3.                          EPP V1.4d.  E Preprocessor.
  4.            Copyright ©1993-1994 Barry Wills.  All rights reserved.
  5.  
  6.  
  7. ============================================================================
  8.  
  9.  
  10. DISTRIBUTION.
  11. ~~~~~~~~~~~~
  12.    This product may be freely distributed under the following restrictions:
  13.  
  14.    1.  The complete contents of the original archive must remain intact.
  15.    2.  The original material may in no way be modified.
  16.    3.  This product may not be distributed for profit.  A nominal copying
  17.        fee is authorized (for cost of materials and shipping and handling
  18.        comparable to that charged by Fred Fish.)
  19.    4.  Commercial distribution of this product without written permission
  20.        from the author is forbidden.
  21.  
  22.  
  23.  
  24. USE OF THIS PRODUCT.
  25. ~~~~~~~~~~~~~~~~~~~
  26.    This product may be used under the following restrictions:
  27.  
  28.    1.  Non-commercial use of this product is free of charge.
  29.    2.  Commercial use of this product without written permission from the
  30.        author is forbidden.
  31.    3.  This product may not be used for malicious intent.
  32.  
  33.  
  34.  
  35. DISCLAIMER.
  36. ~~~~~~~~~~
  37.    This product is provided without any warranty, express or implied.  The
  38.    user of this product assumes full responsibility for any damage resulting
  39.    from the use and/or misuse of this product.  Whaddya want for free? :-)
  40.  
  41.  
  42.  
  43. CONTENTS.
  44. ~~~~~~~~
  45.    This archive should contain the following:
  46.  
  47.      EPP              - Executable v1.4c
  48.      ShowMap          - Displays the module map which is produced and used
  49.                         by EPP to report errors
  50.      EPP.doc          - Copyright notice and product information (this file)
  51.      EPP.history      - Revision history
  52.      EHS.lzh          - EHS, E Header System (thanks Chad!)
  53.      Source           - Directory containing EPP.e, ShowMap.e, reportError.e
  54.                         pmodule, ReportErrorTest.e, and other example sources
  55.      Fishcon.txt      - Short program description
  56.      FreshFish.txt    - KingFisher file description
  57.      Readme_First.doc - Getting started quickly
  58.      Pmodules/*       - REAL-WORLD modules, RUH!
  59.      Scripts/Mac2E!   - Example script to use with the -x switch.
  60.  
  61.  
  62. ============================================================================
  63.  
  64.  
  65. WHAT'S NEW?
  66. ~~~~~~~~~~
  67.    o  Speed enhancement optimizations.  EPP is now 100%+ faster!
  68.  
  69.    o  Directly calls EC!
  70.  
  71.    o  Accurate reporting of error location:  line number and module name!
  72.  
  73.    o  Reworked command-line:
  74.       -w  for WbToFront() call (default is NO WbToFront());
  75.       -v  option for verbose mode (default is now COMPLETELY silent);
  76.       -b  and -l options are now obsolete;
  77.       -s  saves final output source (default is to DELETE it);
  78.       -m  save EPP module map file
  79.       -n  no compilation (EC called by default);
  80.       -e  pass args to EC;
  81.       -x  execute intermediate command, after preprocessing and before
  82.           compilation;
  83.  
  84.    o  Many new PModules!  (Hey, easily ported to E v3.0 modules!!!)
  85.  
  86.    o  Fixed a nasty bug that hung-n-crashed when the last line in a source
  87.       file didn't end in LF.  As a side effect, this fixes EC's problem
  88.       with ignoring missing ENDPROC.  (This happens when you type the last
  89.       ENDPROC in your source, and your editor trusts that since you didn't
  90.       type a return there, you don't want an LF.  Compiles okay, but crashes
  91.       upon exiting your program...very tough boag to hunt since LFs are
  92.       usually invisible :-)
  93.  
  94.    o  Fixed lotsa minor bugs.  EPP v1.3 (not released) took many liberties
  95.       with source which could turn out bad under some curcumstances.
  96.       These were eliminated and some more checks were put in.
  97.  
  98.    o  Enhanced parsing of PMODULE statement, now allows multi-name module
  99.       lists (e.g., PMODULE 'x', 'y', 'z').
  100.  
  101.    o  Prevents duplicate MODULE declarations (circumvents E21b's double-
  102.       library-module-inclusion bug-bites)!
  103.  
  104.    o  Handles E's future single-line comment symbol "->".  (Why?  'cause
  105.       it was no extra work, really. :-)
  106.  
  107.  
  108. REQUIREMENTS.
  109. ~~~~~~~~~~~~
  110.    An Amiga with at least 1Meg of RAM.  I have tested EPP inside of about
  111.    500K, and EPP processed itself with little room to spare.
  112.  
  113.    Of course, you will also need Wouter van Oortmerssen's Amiga E V2.1b or
  114.    better.  At the time of this release, Amiga E V2.1b is the most recent.
  115.    (NOTE: the Amiga E compiler requires at least 1Meg of RAM to be able to
  116.    do anything meaningful.)
  117.  
  118.    The AmigaDOS Run command and the AmigaE compiler EC must be in your path.
  119.  
  120.    An assignment to T: with enough storage to accommodate temporary files
  121.    (recommended in ram for speed).
  122.  
  123.  **EPP should not be KickStart dependent.  (If you find it is, please let
  124.    me know!)
  125.  
  126.  
  127.  
  128. DESCRIPTION.
  129. ~~~~~~~~~~~
  130.    EPP is an E project development tool which allows an E application to be
  131.    developed in a modular fashion.  Use of this tool contributes towards
  132.    some important software engineering concepts, namely reusability and
  133.    modularity.  Anyone who has tried to write a respectable application in a
  134.    language which doesn't support modules can attest to the unwieldiness of
  135.    a huge main program file.  And anyone who has written multiple
  136.    applications in a language which supports modules can attest to the
  137.    luxury of being able to reuse source components without having to block-
  138.    copy source code from several locations.
  139.  
  140.    EPP has been designed with simplicity in mind, so that only minimal
  141.    changes should be required to source code in order to become compatible
  142.    with future releases of E which allow modules.  At that time, EPP may
  143.    respectfully retire. :-)
  144.  
  145.    NOTE:  Some features exist which will not be portable to E v3.0 at all,
  146.    namely the "OPT TURBO" directive, and the capability to have a
  147.    PROC main() in Pmodules.
  148.  
  149.  
  150.            /*---------------------------------------------*/
  151.            /*--  ENOUGH!!!  HOW DO I USE THIS THING???  --*/
  152.            /*---------------------------------------------*/
  153.  
  154.  
  155.  
  156. USAGE.
  157. ~~~~~
  158.    Invocation:  EPP [options] in[.e] [out[.e]] [-xCOMMAND]
  159.        in  = path/filename of the main program, '.e' extension is optional.
  160.        out = optional path/filename to use for the temp source file, which
  161.              will (hopefully) be suitable for compilation with EC, the E
  162.              compiler.  Default filename is main_temp.e.
  163.    Options:
  164.        -v            = verbose;
  165.        -c            = insert EPP comments in final output source;
  166.        -t            = Turbo mode;
  167.        -w            = Workbench to front (for scripts);
  168.        -s            = save temp source file;
  169.        -m            = save EPP module map file;
  170.        -n            = no compilation;
  171.        -e[lanrwsbmX] = EC options, see E Compiler.doc;
  172.        -xCOMMAND     = intermediate command (must be last);
  173.  
  174.    EPP allows primitive inclusion of user pseudo-modules.  EPP pseudo-
  175.    modules are E source code.  EPP is similar to a C preprocessor in that it
  176.    merges source code as specified by module inclusion directives entered
  177.    into the source code.  Module inclusion directives use the following
  178.    notation:
  179.  
  180.      PMODULE 'dev:path/filename_1' [,'dev:path/filename_2] [...]
  181.  
  182.    The keyword PMODULE is required.  The optional 'dev:' is any valid
  183.    logical DOS device.  'Path' is the optional subdirectory in which the
  184.    module can be found.  'Filename' is the name of the module file without
  185.    the '.e' extension.  The '.e' extension is added automatically by EPP.
  186.    The PMODULE statement may span multiple lines in the same fashion as the
  187.    E MODULE statement.  (NOTE:  EPP does not use a default logical device or
  188.    directory to locate modules.  The device and path must always be specified
  189.    if the modules are not in the current directory.)
  190.  
  191.    EPP will merge all global declarations in the order of dependency as
  192.    determined by the PMODULE statements:  first come, first serve.  EPP will
  193.    then merge all procedures and functions in the same order.
  194.  
  195.    The final output file contains all modules' comments.  Additional module
  196.    information is inserted at strategic locations by EPP if the -c switch is
  197.    specified on the command line.
  198.  
  199.    See the two examples directories supplied with this package.  EPP_Example1
  200.    attempts to simulate the structure of a real project.  EPP_Example2
  201.    contains examples of how to use some of the modules provided in the
  202.    PModules directory.
  203.  
  204.  
  205.  
  206. PROGRAM STRUCTURE.
  207. ~~~~~~~~~~~~~~~~~
  208.    PMODULE statements can be put anywhere (see the "NOTE ON TURBO MODE"
  209.    below for a caveat.)  The only thing you have to mind is that the modules
  210.    containing types, constants, and variables needed by subsequent modules
  211.    must be included first, otherwise EC will inform you of the error.  The
  212.    general format of a main program is:
  213.  
  214.    You have a lot of flexibility in placement of modules.  EPP locates any
  215.    module declarations at the front of the final output file, and the
  216.    procedures are inserted at the place of module declaration.  Pseudo-
  217.    modules MAY BE NESTED AS DEEPLY AS RESOURCES WILL PERMIT, i.e., as long
  218.    as you have enough stack and memory you can have PMODULEs within PMODULEs
  219.    within PMODULEs...
  220.  
  221.  
  222.  
  223. OTHER CONSIDERATIONS.
  224. ~~~~~~~~~~~~~~~~~~~~
  225.    TURBO MODE:  Turbo mode does *not* recognize PMODULE statements that
  226.    occur after the first PROC statement in a module.  Turbo mode does *not*
  227.    check for duplicate PROC main()s in modules.  The reason for this is
  228.    speed.  Turbo mode does *NO PARSING* of the procs section of modules.
  229.  
  230.    OPT TURBO:  this directive starts TURBO mode within a single module for
  231.    the duration of that module.  It can be placed anywhere in a module
  232.    outside of a PROC..ENDPROC.  The Turbo routine will be invoked upon the
  233.    next occurrence of the PROC keyword.  OPT TURBO must, of course, be
  234.    uncommented.  It may be placed as far down in the module as desired.  Only
  235.    one OPT TURBO directive should be used within a module file since
  236.    subsequent occurrences will not be parsed once the Turbo routine is
  237.    invoked, and EC will not recognize "OPT TURBO".
  238.  
  239.                           *    *    *    *    *
  240.  
  241.    EPP is *NOT* like the COBOL COPY statement.  Any global definitions and
  242.    declarations in a module are moved to the global section of the main
  243.    program.
  244.  
  245.                           *    *    *    *    *
  246.  
  247.    EPP tries to be smart about what it is reading.  It is not, however, a
  248.    full-blown syntax checker.  EPP relies on good syntax in your modules, so
  249.    you should test modules for syntax before using them with EPP.  This will
  250.    reduce the risk of brain damage. :)
  251.  
  252.                           *    *    *    *    *
  253.  
  254.    EPP allows you to keep a PROC main() in all modules to facilitate ease
  255.    of testing.  Any PROC main() encountered in modules other than the main
  256.    module are omitted, and, if EPP comments are turned on, an E comment is
  257.    inserted in the final output file to indicate this.  This can be quite
  258.    handy while testing a module since E requires a PROC main() in order to
  259.    compile the module.  EPP saves you the hassle of commenting and
  260.    uncommenting code in your source module during development.  (HINT:  place
  261.    all test PROCs after PROC main() and EPP will ignore them.  Likewise, if
  262.    you want PROCs recognized by EPP, don't put them after a PROC main() in
  263.    your modules.)  THIS FEATURE IS NOT AVAILABLE IF YOU CHOOSE TO USE THE
  264.    TURBO OPTION IN A MODULE.  (HINT:  use the OPT TURBO directive in modules
  265.    that don't need this feature to speed up processing.  Duplicate PROC
  266.    main()s will still be omitted in modules not using OPT TURBO.)
  267.  
  268.                           *    *    *    *    *
  269.  
  270.    Since EPP is simply a sophisticated text file merger, it is up to you to
  271.    ensure that all your modules' identifiers are unique.  If they are not,
  272.    the E compiler will inform you of the duplicate identifiers.
  273.  
  274.                           *    *    *    *    *
  275.  
  276.    Using the -x switch takes some consideration.  EPP makes no assumptions
  277.    about what intermediate command might be issued.  EPP expects that after
  278.    your intermediate command operates the temp file (default temp_main.e),
  279.    the modified source will be found under the same file name as the temp
  280.    file.  Therefore, if your command creates a processed file that is
  281.    differently named, you must rename or copy it back to the temp file.
  282.    See the included shell script Mac2E! for an example of this process.
  283.  
  284.  
  285.  
  286. ============================================================================
  287.  
  288.  
  289. LIMITATIONS.
  290. ~~~~~~~~~~~
  291.     - If you like to put comments outside of PROCs you will notice that some
  292.       of them don't end up where you'd like, especially those that follow
  293.       the global declarative section.  See Example1 project, module 'mod2.e'
  294.       for a demonstration of this phenomenon.  EPP thinks that everything
  295.       before the first PROC belongs to the global declaratives.  (HINT:  keep
  296.       your modules small and put your comments *inside* the PROC, immediately
  297.       following the headers.)
  298.  
  299.  
  300.  
  301. ============================================================================
  302.  
  303.  
  304. MISCELLANEOUS.
  305. ~~~~~~~~~~~~~
  306. This product was developed in Amiga E language and tested on a Commodore
  307. Amiga 500 with the following configuration:
  308.  
  309.    KickStart V1.3, WorkBench V1.3, ©Commodore-Amiga, Inc.
  310.    KickStart V2.04, WorkBench V2.1, ©Commodore-Amiga, Inc.
  311.    Amiga E V2.1, ©Wouter van Oortmerssen
  312.  
  313.    DataFlyer 500 SCSI controller
  314.    Quantum 52M HD
  315.    Dual 880K floppy drive
  316.    1M 16-bit Chip RAM
  317.    CSA Derringer 030 accellerator:
  318.       68030 CPU @25MHz
  319.       68881 FPU @27MHz
  320.       4M 32-bit Fast RAM
  321.  
  322.    Caffiene
  323.    Sugar
  324.    Amino Acid Tablets
  325.    Hard Rock and Metal
  326.  
  327.  
  328. ============================================================================
  329.  
  330.  
  331. CREDITS.
  332. ~~~~~~~
  333.   - Special thanks to Chad Freeman for permission to include EHS, his E Header
  334.     System!  (The incomplete docs are *his* fault, though! :-) :-)
  335.  
  336.   - Special thanks to the dauntless EPP beta testers:  Matthew Hornyak, Mark
  337.     Langston, Alex McCracken, Jessie Thornton, and Lionel Vintenat!  (In
  338.     alpha-ascending order of surname.)
  339.  
  340.   - Special thanks to Alex McCracken for really putting EPP through the
  341.     wringer.  Great work, Alex!
  342.  
  343.   - Special thanks to Lionel Vintenat for many, many wonderful suggestions!
  344.  
  345.   - Special Wouter van Oortmerssen for Amiga E!  (And for revealing to me
  346.     the insidious, ubiquitous, sideways smiley face :)
  347.  
  348.  
  349.  
  350. ============================================================================
  351.  
  352.  
  353. CONTACTING THE AUTHOR.
  354. ~~~~~~~~~~~~~~~~~~~~~
  355. I can be reached by the following means:
  356.  
  357.   Internet:  el269@cleveland.freenet.edu
  358.  
  359.   USnail:    Barry Wills
  360.              5528D Pryor Dr.
  361.              Scott AFB, IL 62225 (USA)
  362.              (618)-744-1096
  363.  
  364. I originally wrote EPP for my own use.  It's very fulfilling to author
  365. something that others enjoy as much as I do, hence this update (which I
  366. never expected to produce :)  Thanks to all those who mailed me comments,
  367. suggestions, and compliments!  Please send mail, money, software, warm
  368. weather to the address(es) above.  I am very interested in feedback; I
  369. will answer all mail.  Good luck and enjoy!
  370.  
  371.   -- Barry
  372.  
  373.  
  374.  
  375. ============================================================================
  376.  
  377.